home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / include / xpcom / nsXPCOM.h < prev    next >
C/C++ Source or Header  |  2006-05-08  |  15KB  |  422 lines
  1. /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is mozilla.org code.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1998
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *   Benjamin Smedberg <benjamin@smedbergs.us>
  24.  *
  25.  * Alternatively, the contents of this file may be used under the terms of
  26.  * either of the GNU General Public License Version 2 or later (the "GPL"),
  27.  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28.  * in which case the provisions of the GPL or the LGPL are applicable instead
  29.  * of those above. If you wish to allow use of your version of this file only
  30.  * under the terms of either the GPL or the LGPL, and not to allow others to
  31.  * use your version of this file under the terms of the MPL, indicate your
  32.  * decision by deleting the provisions above and replace them with the notice
  33.  * and other provisions required by the GPL or the LGPL. If you do not delete
  34.  * the provisions above, a recipient may use your version of this file under
  35.  * the terms of any one of the MPL, the GPL or the LGPL.
  36.  *
  37.  * ***** END LICENSE BLOCK ***** */
  38.  
  39. #ifndef nsXPCOM_h__
  40. #define nsXPCOM_h__
  41.  
  42. // Map frozen functions to private symbol names if not using strict API.
  43. #ifdef MOZILLA_INTERNAL_API
  44. # define NS_InitXPCOM2               NS_InitXPCOM2_P
  45. # define NS_InitXPCOM3               NS_InitXPCOM3_P
  46. # define NS_ShutdownXPCOM            NS_ShutdownXPCOM_P
  47. # define NS_GetServiceManager        NS_GetServiceManager_P
  48. # define NS_GetComponentManager      NS_GetComponentManager_P
  49. # define NS_GetComponentRegistrar    NS_GetComponentRegistrar_P
  50. # define NS_GetMemoryManager         NS_GetMemoryManager_P
  51. # define NS_NewLocalFile             NS_NewLocalFile_P
  52. # define NS_NewNativeLocalFile       NS_NewNativeLocalFile_P
  53. # define NS_GetDebug                 NS_GetDebug_P
  54. # define NS_GetTraceRefcnt           NS_GetTraceRefcnt_P
  55. # define NS_Alloc                    NS_Alloc_P
  56. # define NS_Realloc                  NS_Realloc_P
  57. # define NS_Free                     NS_Free_P
  58. #endif
  59.  
  60. #include "nscore.h"
  61. #include "nsXPCOMCID.h"
  62.  
  63. class nsAString;
  64. class nsACString;
  65.  
  66. class nsIModule;
  67. class nsIComponentManager;
  68. class nsIComponentRegistrar;
  69. class nsIServiceManager;
  70. class nsIFile;
  71. class nsILocalFile;
  72. class nsIDirectoryServiceProvider;
  73. class nsIMemory;
  74. class nsIDebug;
  75. class nsITraceRefcnt;
  76.  
  77. /**
  78.  * Every XPCOM component implements this function signature, which is the
  79.  * only entrypoint XPCOM uses to the function.
  80.  *
  81.  * @status FROZEN
  82.  */
  83. typedef nsresult (PR_CALLBACK *nsGetModuleProc)(nsIComponentManager *aCompMgr,
  84.                                                 nsIFile* location,
  85.                                                 nsIModule** return_cobj);
  86.  
  87. /**
  88.  * Initialises XPCOM. You must call one of the NS_InitXPCOM methods
  89.  * before proceeding to use xpcom. The one exception is that you may
  90.  * call NS_NewLocalFile to create a nsIFile.
  91.  * 
  92.  * @status FROZEN
  93.  *
  94.  * @note Use <CODE>NS_NewLocalFile</CODE> or <CODE>NS_NewNativeLocalFile</CODE> 
  95.  *       to create the file object you supply as the bin directory path in this
  96.  *       call. The function may be safely called before the rest of XPCOM or 
  97.  *       embedding has been initialised.
  98.  *
  99.  * @param result           The service manager.  You may pass null.
  100.  *
  101.  * @param binDirectory     The directory containing the component
  102.  *                         registry and runtime libraries;
  103.  *                         or use <CODE>nsnull</CODE> to use the working
  104.  *                         directory.
  105.  *
  106.  * @param appFileLocationProvider The object to be used by Gecko that specifies
  107.  *                         to Gecko where to find profiles, the component
  108.  *                         registry preferences and so on; or use
  109.  *                         <CODE>nsnull</CODE> for the default behaviour.
  110.  *
  111.  * @see NS_NewLocalFile
  112.  * @see nsILocalFile
  113.  * @see nsIDirectoryServiceProvider
  114.  *
  115.  * @return NS_OK for success;
  116.  *         NS_ERROR_NOT_INITIALIZED if static globals were not initialized,
  117.  *         which can happen if XPCOM is reloaded, but did not completly
  118.  *         shutdown. Other error codes indicate a failure during
  119.  *         initialisation.
  120.  */
  121. extern "C" NS_COM nsresult
  122. NS_InitXPCOM2(nsIServiceManager* *result, 
  123.               nsIFile* binDirectory,
  124.               nsIDirectoryServiceProvider* appFileLocationProvider);
  125.  
  126. /**
  127.  * Some clients of XPCOM have statically linked components (not dynamically
  128.  * loaded component DLLs), which can be passed to NS_InitXPCOM3 using this
  129.  * structure.
  130.  *
  131.  * @status FROZEN
  132.  */
  133. struct nsStaticModuleInfo {
  134.   const char      *name;
  135.   nsGetModuleProc  getModule;
  136. };
  137.  
  138. /**
  139.  * Initialises XPCOM with static components. You must call one of the
  140.  * NS_InitXPCOM methods before proceeding to use xpcom. The one
  141.  * exception is that you may call NS_NewLocalFile to create a nsIFile.
  142.  * 
  143.  * @status FROZEN
  144.  *
  145.  * @note Use <CODE>NS_NewLocalFile</CODE> or <CODE>NS_NewNativeLocalFile</CODE> 
  146.  *       to create the file object you supply as the bin directory path in this
  147.  *       call. The function may be safely called before the rest of XPCOM or 
  148.  *       embedding has been initialised.
  149.  *
  150.  * @param result           The service manager.  You may pass null.
  151.  *
  152.  * @param binDirectory     The directory containing the component
  153.  *                         registry and runtime libraries;
  154.  *                         or use <CODE>nsnull</CODE> to use the working
  155.  *                         directory.
  156.  *
  157.  * @param appFileLocationProvider The object to be used by Gecko that specifies
  158.  *                         to Gecko where to find profiles, the component
  159.  *                         registry preferences and so on; or use
  160.  *                         <CODE>nsnull</CODE> for the default behaviour.
  161.  *
  162.  * @param staticComponents An array of static components. Passing null causes
  163.  *                         default (builtin) components to be registered, if
  164.  *                         present.
  165.  * @param componentCount   Number of elements in staticComponents
  166.  *
  167.  * @see NS_NewLocalFile
  168.  * @see nsILocalFile
  169.  * @see nsIDirectoryServiceProvider
  170.  * @see XRE_GetStaticComponents
  171.  *
  172.  * @return NS_OK for success;
  173.  *         NS_ERROR_NOT_INITIALIZED if static globals were not initialized,
  174.  *         which can happen if XPCOM is reloaded, but did not completly
  175.  *         shutdown. Other error codes indicate a failure during
  176.  *         initialisation.
  177.  */
  178. extern "C" NS_COM nsresult
  179. NS_InitXPCOM3(nsIServiceManager* *result, 
  180.               nsIFile* binDirectory,
  181.               nsIDirectoryServiceProvider* appFileLocationProvider,
  182.               nsStaticModuleInfo const *staticComponents,
  183.               PRUint32 componentCount);
  184.  
  185. /**
  186.  * Shutdown XPCOM. You must call this method after you are finished
  187.  * using xpcom. 
  188.  *
  189.  * @status FROZEN
  190.  *
  191.  * @param servMgr           The service manager which was returned by NS_InitXPCOM.
  192.  *                          This will release servMgr.  You may pass null.
  193.  *
  194.  * @return NS_OK for success;
  195.  *         other error codes indicate a failure during initialisation.
  196.  *
  197.  */
  198. extern "C" NS_COM nsresult
  199. NS_ShutdownXPCOM(nsIServiceManager* servMgr);
  200.  
  201.  
  202. /**
  203.  * Public Method to access to the service manager.
  204.  * 
  205.  * @status FROZEN
  206.  * @param result Interface pointer to the service manager 
  207.  *
  208.  * @return NS_OK for success;
  209.  *         other error codes indicate a failure during initialisation.
  210.  *
  211.  */
  212. extern "C" NS_COM nsresult
  213. NS_GetServiceManager(nsIServiceManager* *result);
  214.  
  215. /**
  216.  * Public Method to access to the component manager.
  217.  * 
  218.  * @status FROZEN
  219.  * @param result Interface pointer to the service 
  220.  *
  221.  * @return NS_OK for success;
  222.  *         other error codes indicate a failure during initialisation.
  223.  *
  224.  */
  225. extern "C" NS_COM nsresult
  226. NS_GetComponentManager(nsIComponentManager* *result);
  227.  
  228. /**
  229.  * Public Method to access to the component registration manager.
  230.  * 
  231.  * @status FROZEN
  232.  * @param result Interface pointer to the service 
  233.  *
  234.  * @return NS_OK for success;
  235.  *         other error codes indicate a failure during initialisation.
  236.  *
  237.  */
  238. extern "C" NS_COM nsresult
  239. NS_GetComponentRegistrar(nsIComponentRegistrar* *result);
  240.  
  241. /**
  242.  * Public Method to access to the memory manager.  See nsIMemory
  243.  * 
  244.  * @status FROZEN
  245.  * @param result Interface pointer to the memory manager 
  246.  *
  247.  * @return NS_OK for success;
  248.  *         other error codes indicate a failure during initialisation.
  249.  *
  250.  */
  251. extern "C" NS_COM nsresult
  252. NS_GetMemoryManager(nsIMemory* *result);
  253.  
  254. /**
  255.  * Public Method to create an instance of a nsILocalFile.  This function
  256.  * may be called prior to NS_InitXPCOM.
  257.  * 
  258.  * @status FROZEN
  259.  * 
  260.  *   @param path       
  261.  *       A string which specifies a full file path to a 
  262.  *       location.  Relative paths will be treated as an
  263.  *       error (NS_ERROR_FILE_UNRECOGNIZED_PATH).       
  264.  *       |NS_NewNativeLocalFile|'s path must be in the 
  265.  *       filesystem charset.
  266.  *   @param followLinks
  267.  *       This attribute will determine if the nsLocalFile will auto
  268.  *       resolve symbolic links.  By default, this value will be false
  269.  *       on all non unix systems.  On unix, this attribute is effectively
  270.  *       a noop.  
  271.  * @param result Interface pointer to a new instance of an nsILocalFile 
  272.  *
  273.  * @return NS_OK for success;
  274.  *         other error codes indicate a failure.
  275.  */
  276.  
  277. extern "C" NS_COM nsresult
  278. NS_NewLocalFile(const nsAString &path, 
  279.                 PRBool followLinks, 
  280.                 nsILocalFile* *result);
  281.  
  282. extern "C" NS_COM nsresult
  283. NS_NewNativeLocalFile(const nsACString &path, 
  284.                       PRBool followLinks, 
  285.                       nsILocalFile* *result);
  286.  
  287. /**
  288.  * Allocates a block of memory of a particular size. If the memory cannot
  289.  * be allocated (because of an out-of-memory condition), null is returned.
  290.  *
  291.  * @status FROZEN
  292.  *
  293.  * @param size   The size of the block to allocate
  294.  * @result       The block of memory
  295.  * @note         This function is thread-safe.
  296.  */
  297. extern "C" NS_COM void*
  298. NS_Alloc(PRSize size);
  299.  
  300. /**
  301.  * Reallocates a block of memory to a new size.
  302.  *
  303.  * @status FROZEN
  304.  *
  305.  * @param ptr     The block of memory to reallocate. This block must originally
  306.                   have been allocated by NS_Alloc or NS_Realloc
  307.  * @param size    The new size. If 0, frees the block like NS_Free
  308.  * @result        The reallocated block of memory
  309.  * @note          This function is thread-safe.
  310.  *
  311.  * If ptr is null, this function behaves like NS_Alloc.
  312.  * If s is the size of the block to which ptr points, the first min(s, size)
  313.  * bytes of ptr's block are copied to the new block. If the allocation
  314.  * succeeds, ptr is freed and a pointer to the new block is returned. If the
  315.  * allocation fails, ptr is not freed and null is returned. The returned
  316.  * value may be the same as ptr.
  317.  */
  318. extern "C" NS_COM void*
  319. NS_Realloc(void* ptr, PRSize size);
  320.  
  321. /**
  322.  * Frees a block of memory. Null is a permissible value, in which case no
  323.  * action is taken.
  324.  *
  325.  * @status FROZEN
  326.  *
  327.  * @param ptr   The block of memory to free. This block must originally have
  328.  *              been allocated by NS_Alloc or NS_Realloc
  329.  * @note        This function is thread-safe.
  330.  */
  331. extern "C" NS_COM void
  332. NS_Free(void* ptr);
  333.  
  334.  
  335. /**
  336.  * Categories (in the category manager service) used by XPCOM:
  337.  */
  338.  
  339. /**
  340.  * A category which is read after component registration but before
  341.  * the "xpcom-startup" notifications. Each category entry is treated
  342.  * as the contract ID of a service which implements
  343.  * nsIDirectoryServiceProvider. Each directory service provider is
  344.  * installed in the global directory service.
  345.  *
  346.  * @status FROZEN
  347.  */
  348. #define XPCOM_DIRECTORY_PROVIDER_CATEGORY "xpcom-directory-providers"
  349.  
  350. /**
  351.  * A category which is read after component registration but before
  352.  * NS_InitXPCOM returns. Each category entry is treated as the contractID of
  353.  * a service: each service is instantiated, and if it implements nsIObserver
  354.  * the nsIObserver.observe method is called with the "xpcom-startup" topic.
  355.  *
  356.  * @status FROZEN
  357.  */
  358. #define NS_XPCOM_STARTUP_CATEGORY "xpcom-startup"
  359.  
  360.  
  361. /**
  362.  * Observer topics (in the observer service) used by XPCOM:
  363.  */
  364.  
  365. /**
  366.  * At XPCOM startup after component registration is complete, the
  367.  * following topic is notified. In order to receive this notification,
  368.  * component must register their contract ID in the category manager,
  369.  *
  370.  * @see NS_XPCOM_STARTUP_CATEGORY
  371.  * @status FROZEN
  372.  */
  373. #define NS_XPCOM_STARTUP_OBSERVER_ID "xpcom-startup"
  374.  
  375. /**
  376.  * At XPCOM shutdown, this topic is notified. All components must
  377.  * release any interface references to objects in other modules when
  378.  * this topic is notified.
  379.  *
  380.  * @status FROZEN
  381.  */
  382. #define NS_XPCOM_SHUTDOWN_OBSERVER_ID "xpcom-shutdown"
  383.  
  384. /**
  385.  * This topic is notified when an entry was added to a category in the
  386.  * category manager. The subject of the notification will be the name of
  387.  * the added entry as an nsISupportsCString, and the data will be the
  388.  * name of the category.
  389.  *
  390.  * @status FROZEN
  391.  */
  392. #define NS_XPCOM_CATEGORY_ENTRY_ADDED_OBSERVER_ID \
  393.   "xpcom-category-entry-added"
  394.  
  395. /**
  396.  * This topic is notified when an entry was removed from a category in the
  397.  * category manager. The subject of the notification will be the name of
  398.  * the removed entry as an nsISupportsCString, and the data will be the
  399.  * name of the category.
  400.  *
  401.  * @status FROZEN
  402.  */
  403. #define NS_XPCOM_CATEGORY_ENTRY_REMOVED_OBSERVER_ID \
  404.   "xpcom-category-entry-removed"
  405.  
  406. /**
  407.  * This topic is notified when an a category was cleared in the category
  408.  * manager. The subject of the notification will be the category manager,
  409.  * and the data will be the name of the cleared category.
  410.  *
  411.  * @status FROZEN
  412.  */
  413. #define NS_XPCOM_CATEGORY_CLEARED_OBSERVER_ID "xpcom-category-cleared"
  414.  
  415. extern "C" NS_COM nsresult
  416. NS_GetDebug(nsIDebug* *result);
  417.  
  418. extern "C" NS_COM nsresult
  419. NS_GetTraceRefcnt(nsITraceRefcnt* *result);
  420.  
  421. #endif
  422.